Summary

Closes #2.

Adds a per-tool optimizer finding for MCP servers whose schema is loaded on every turn but rarely invoked. Builds on the existing server-level detectUnusedMcp (zero invocations) by reporting partial-use cases like "loaded 54 tools, called 0" or "loaded 26 tools, called 2 (8% coverage)".

Smoke-tested on a real account: 7 servers flagged across 93 sessions — office-word-mcp 0/54, notebooklm-mcp 0/38, office-ppt-mcp 0/37, excel-mcp-server 0/25, github-mcp-server 2/26, peekaboo 3/22, plus claude_ai_Asana.

Inventory source

Claude Code's JSONL writes attachment.deferred_tools_delta entries whose addedNames array lists the exact tools available at that turn — including every fully-qualified mcp__<server>__<tool> name. We union across all delta entries in a session (not just the first) because tool availability can change mid-session when MCP config reloads or a subagent inherits a different tool set.

Names that don't match the mcp__<server>__<tool> shape with both segments non-empty are rejected at extraction so downstream split('__') consumers can't be poisoned.

Token-savings estimation

MCP tool schemas live in the cached prefix of the system prompt:

• Each cache-creation event (rebuilds happen every ~5 minutes of inactivity) pays the full input price.
• Subsequent turns pay the cache-read discount (~10% of input).
• Each call's contribution is capped at its observed cacheCreationInputTokens / cacheReadInputTokens so we never claim more MCP overhead than the call's own cache buckets could contain.

When multiple servers are flagged, costing is a single combined pass: the per-call cap applies to the total unused-schema budget across all flagged servers, not per server. Two flagged servers can't independently claim the same call's cache bucket and overstate tokensSaved.

Correctness invariants

• A session counts toward loadedSessions (and toward the cost estimate) only if its observed inventory included the server. Pure invocation-only sessions, where the server appears in mcpBreakdown or call.mcpTools without any matching deferred_tools_delta, do not satisfy the >= 2 sessions threshold on their own.
• Coverage is computed against the inventory only: invocations of names not present in any observed inventory (older config, hallucinated tool, typo) do not inflate toolsInvoked and cannot drive unusedCount negative. toolsInvoked is derived as inventory.size - unusedTools.length to keep both numbers consistent.
• detectUnusedMcp and the new detector are explicitly disjoint: detectUnusedMcp skips servers that the coverage detector will actually report (i.e. those clearing its thresholds), not every server that happens to be in any inventory. A small inventoried-but-uninvoked server below the coverage thresholds still gets flagged as "configured but never called."

Thresholds

• > 10 tools available (small servers are noise)
• < 20% coverage
• >= 2 sessions with observed inventory
• High impact when total effective tokens >= 200_000 or >= 3 servers flagged

Changes

• src/types.ts: optional mcpInventory: string[] on SessionSummary. Provider-agnostic field; currently populated only by the Claude parser.
• src/parser.ts: extractMcpInventory walks all entries, validates fully-qualified names, returns sorted unique list. buildSessionSummary passes it through; the field is omitted when empty so JSON exports stay clean.
• src/optimize.ts: aggregateMcpCoverage, estimateMcpSchemaCost (single- and multi-server signatures), detectMcpToolCoverage. Wired into scanAndDetect. detectUnusedMcp updated to be disjoint with the new detector.
• tests/mcp-coverage.test.ts: 23 cases covering aggregation, costing, combined-cap behaviour, threshold gates, invocation-only-session filtering, foreign-tool invocations, cache rebuild events, write+read on the same call, multi-server pluralisation, backward-compat single-server signature.
• tests/parser-mcp-inventory.test.ts: 12 cases for the JSONL extractor including malformed name rejection (mcp__server, mcp__server__, mcp____tool) and tolerant attachment parsing.
• CHANGELOG.md: entry under Unreleased / Added (CLI).

Scope notes

• Claude-only. deferred_tools_delta is Claude Code-specific. The field is provider-agnostic on SessionSummary so other parsers can populate it later, but no other provider exposes the same telemetry today.
• No public API change beyond the new mcpInventory optional field. All existing schemas, exports, and CLI flags are unaffected.
• No dashboard panel in this PR. The optimizer is the lowest-friction surfacing path, which fits the existing waste-finding model. Open to following up with a panel if you'd like.

Test plan

npx tsc --noEmit       # 0 errors
npx vitest run         # 34 files, 462 passed (was 427 baseline + 35 new)
npm run build          # success
node dist/cli.js optimize -p week
# -> "7 MCP servers with low tool coverage" finding (High)
# -> existing "configured but never used" still flags servers below the
#    coverage thresholds (e.g. `oura` in my data)

Reviews considered

Design and implementation went through three rounds of code review (Codex GPT-5.5 high, Gemini 3.1 Pro Preview, an internal Sonnet reviewer) before this PR. Concrete findings addressed end-to-end:

• Duplicate findings between the legacy and new detector
• loadedSessions counted from invocation-only sessions, diluting the threshold
• toolsInvoked counting tools not present in inventory
• continue after cacheCreationInputTokens skipping the same call's cacheReadInputTokens
• extractMcpInventory accepting malformed names
• Cache rebuilds (multiple cacheCreation events per session)
• Cumulative tokensSaved over-count when multiple servers flagged share a cache bucket
• Inventory-vs-breakdown semantic mismatch between aggregator and cost estimator
• Blind spot in detectUnusedMcp for inventoried-but-uninvoked small servers